Add contribution guidelines for experimental features by kaix-nv · Pull Request #867 · NVIDIA/Model-Optimizer

kaix-nv · 2026-02-06T22:01:16Z

What does this PR do?

Type of change: ?

Overview: ?

Usage

# Add a code snippet demonstrating how to use this

Testing

Before your PR is "Ready for review"

Make sure you read and follow Contributor guidelines and your commits are signed.
Is this change backward compatible?: Yes/No
Did you write any new necessary tests?: Yes/No
Did you add or update any necessary documentation?: Yes/No
Did you update Changelog?: Yes/No

Additional Information

Summary by CodeRabbit

Documentation
- Added comprehensive guide for experimental optimization technique development, including recommended structure, testing conventions, licensing requirements, and graduation path to production.
New Features
- Introduced experimental package with templates and utilities for implementing research-stage optimization techniques. Includes configuration framework and example code patterns. Emits stability warnings to indicate unstable APIs.

coderabbitai · 2026-02-06T22:01:36Z

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

🔍 Trigger a full review

📝 Walkthrough

Walkthrough

This PR establishes a new experimental package with documentation and a template structure for organizing experimental optimization technique prototypes. It includes a package-level README with guidelines and requirements, an experimental module initializer that emits a stability warning, and a template directory containing example configuration, implementation, test, and usage files for new experimental techniques.

Changes

Cohort / File(s)	Summary
Experimental Package Setup `experimental/README.md`, `experimental/__init__.py`	Introduces experimental package documentation outlining structure, requirements, quick-start workflow, and graduation path to production. Package initializer declares empty public API and emits FutureWarning on import.
Template Scaffold `experimental/_template/README.md`, `experimental/_template/__init__.py`, `experimental/_template/config.py`, `experimental/_template/example_usage.py`, `experimental/_template/implementation.py`, `experimental/_template/test_template.py`	Provides template files for new experimental techniques, including Pydantic configuration model with validation, minimal PyTorch example model, basic unit test, and documentation template with customization checklist.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 16.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding contribution guidelines (README, template, and init files) for the experimental features directory.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch kaix/experimental

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@experimental/_template/test_template.py`:
- Line 1: Update the SPDX copyright header in the new test file
(test_template.py) to reflect the correct year (change "2024" to "2026"); locate
the header line with "SPDX-FileCopyrightText" and replace the year portion so
the file's copyright year matches the creation year.

🧹 Nitpick comments (3)

experimental/_template/README.md (1)

14-18: Consider suggesting renaming test_template.py after copying.

Step 3 says to write tests in test_template.py, but after copying the template to experimental/my_technique/, the test file should ideally be renamed to match the new technique (e.g., test_my_technique.py). A brief note would reduce confusion.
experimental/_template/config.py (2)
46-51: TEMPLATE_DEFAULT_CONFIG redundantly restates field defaults.

Since TemplateConfig() with no arguments already produces identical values (all fields have defaults), this constant just duplicates information. It's fine as an illustrative template example, but a comment noting this would help contributors understand the intent is to show the pattern, not that explicit values are required.

40-43: Update class Config to use Pydantic v2 model_config pattern for consistency with the codebase.

The template currently uses the deprecated Pydantic v1-style inner class Config. The codebase already uses the modern Pydantic v2 pattern throughout (see modelopt/torch/opt/config.py, modelopt/torch/distill/config.py, etc.). Update to:
from pydantic import BaseModel, ConfigDict, Field

class TemplateConfig(BaseModel):
    # ... fields ...
    
    model_config = ConfigDict(validate_assignment=True)

coderabbitai · 2026-02-06T22:04:41Z

@@ -0,0 +1,41 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved.


⚠️ Potential issue | 🟡 Minor

Copyright year appears outdated for a newly created file.

This file is being added in 2026 but the copyright header says 2024.

-# SPDX-FileCopyrightText: Copyright (c) 2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

# SPDX-FileCopyrightText: Copyright (c) 2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved.

# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.

🤖 Prompt for AI Agents

In `@experimental/_template/test_template.py` at line 1, Update the SPDX copyright header in the new test file (test_template.py) to reflect the correct year (change "2024" to "2026"); locate the header line with "SPDX-FileCopyrightText" and replace the year portion so the file's copyright year matches the creation year.

shengliangxu · 2026-02-06T22:06:55Z

+```text
+experimental/my_technique/
+├── README.md           # What it does, how to use it
+├── implementation.py   # Core code


I think we should indicate explicitly that a package of code is also allowed.

Added one line: Organize your code as simple files or as a package

shengliangxu · 2026-02-06T22:09:15Z

Overall it looks good as a start.

cjluo-nv · 2026-02-06T22:20:27Z

+optimized = my_optimize(model)
+```
+
+## Status


can we also ask for a model support list as well?

cjluo-nv · 2026-02-06T22:22:39Z

+
+## Requirements
+
+**Must have:**


let's also list an up limit to lines of code for PR contributions. E.g. we cannot accept a feature that has e.g. 100k lines of change etc

cjluo-nv · 2026-02-06T22:23:05Z

+
+- Working code with clear variable names
+- README explaining what it does and how to use it
+- At least one test showing it works


I don't think this is needed for experimental

I actually do not agree. To have an experimental feature to be put into the repo, a piece of illustration code that actually runs is necessary. However, calling it an "example" is better than a "test" in this context.

I think this is required: README should briefly describe the optimization technique and the basic usage.

cjluo-nv · 2026-02-06T22:23:19Z

+**Optional:**
+
+- Comprehensive tests
+- Full documentation


I hope this can be required

cjluo-nv · 2026-02-06T22:23:34Z

+
+- Comprehensive tests
+- Full documentation
+- Pass all pre-commit checks


Can we also make it a requirement?

I think pre-commit should automatically run checks on experimental code

cjluo-nv · 2026-02-06T22:24:59Z

+
+- Novel or research-stage algorithms
+- Not yet production-ready
+- May have unstable APIs


We may also not guarantee experimental features working across releases. user should be with their own to use the experimental features.

Can we also mention that user can request in github issues to promote certain features to be fully integrated so we can use that as a production readiness check.

cjluo-nv · 2026-02-06T22:25:49Z

+
+```text
+experimental/my_technique/
+├── README.md           # What it does, how to use it


What do we want to achieve here by enforcing a template?

IMHO, maybe a clear README.md is all we need?

My plan is to provide a structural guideline for developers. The template might be over-engineering this. If contributors are sophisticated enough to write experimental codes, they can organize their code. I'll remove the template.

codecov · 2026-02-06T22:27:15Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 73.43%. Comparing base (62c2799) to head (5b61480).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #867   +/-   ##
=======================================
  Coverage   73.43%   73.43%           
=======================================
  Files         197      197           
  Lines       20651    20651           
=======================================
  Hits        15166    15166           
  Misses       5485     5485

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

kevalmorabia97 · 2026-02-06T22:52:18Z

Missing requirements.txt marking all additional dependencies than what is already there in modelopt deps

shengliangxu

LGTM as a starting point.

kevalmorabia97 · 2026-02-06T23:14:06Z

+
+## Path to Production
+
+When ready for production (proven effective, stable API, full tests, good docs), open an issue to propose graduating to the main `modelopt` package.


Is this experimental meant for our team or external contributors? Why not have experimental code in a separate feature branch and then merge to main when mature?

It's for external contributors.

Edwardf0t1 · 2026-02-06T23:40:38Z

+- Full documentation
+- Pass all pre-commit checks
+
+## Path to Production


I would ask the authors to provide info on deployment, e.g., any FWs supported with kernel needed.

Good point, added.

Edwardf0t1 · 2026-02-06T23:42:07Z

+
+## References
+
+- Links to papers or related work


code repo, project page if exist

Signed-off-by: Kai Xu <kaix@nvidia.com>

## What does this PR do? **Type of change:** ?  **Overview:** ? ## Usage  ```python # Add a code snippet demonstrating how to use this ``` ## Testing  ## Before your PR is "*Ready for review*"  - **Make sure you read and follow [Contributor guidelines](https://github.com/NVIDIA/Model-Optimizer/blob/main/CONTRIBUTING.md)** and your commits are signed. - **Is this change backward compatible?**: Yes/No  - **Did you write any new necessary tests?**: Yes/No - **Did you add or update any necessary documentation?**: Yes/No - **Did you update [Changelog](https://github.com/NVIDIA/Model-Optimizer/blob/main/CHANGELOG.rst)?**: Yes/No  ## Additional Information   ## Summary by CodeRabbit * **Documentation** * Added comprehensive guide for experimental optimization technique development, including recommended structure, testing conventions, licensing requirements, and graduation path to production. * **New Features** * Introduced experimental package with templates and utilities for implementing research-stage optimization techniques. Includes configuration framework and example code patterns. Emits stability warnings to indicate unstable APIs.  Signed-off-by: Kai Xu <kaix@nvidia.com>

## What does this PR do? **Type of change:** ?  **Overview:** ? ## Usage  ```python # Add a code snippet demonstrating how to use this ``` ## Testing  ## Before your PR is "*Ready for review*"  - **Make sure you read and follow [Contributor guidelines](https://github.com/NVIDIA/Model-Optimizer/blob/main/CONTRIBUTING.md)** and your commits are signed. - **Is this change backward compatible?**: Yes/No  - **Did you write any new necessary tests?**: Yes/No - **Did you add or update any necessary documentation?**: Yes/No - **Did you update [Changelog](https://github.com/NVIDIA/Model-Optimizer/blob/main/CHANGELOG.rst)?**: Yes/No  ## Additional Information   ## Summary by CodeRabbit * **Documentation** * Added comprehensive guide for experimental optimization technique development, including recommended structure, testing conventions, licensing requirements, and graduation path to production. * **New Features** * Introduced experimental package with templates and utilities for implementing research-stage optimization techniques. Includes configuration framework and example code patterns. Emits stability warnings to indicate unstable APIs.  Signed-off-by: Kai Xu <kaix@nvidia.com> Signed-off-by: Daniel Korzekwa <dkorzekwa@nvidia.com>

kaix-nv requested review from Edwardf0t1, cjluo-nv, kevalmorabia97 and shengliangxu February 6, 2026 22:02

coderabbitai bot reviewed Feb 6, 2026

View reviewed changes

shengliangxu reviewed Feb 6, 2026

View reviewed changes

Comment thread experimental/_template/implementation.py Outdated

kaix-nv force-pushed the kaix/experimental branch from 1e10ee4 to 8749208 Compare February 6, 2026 22:15

cjluo-nv reviewed Feb 6, 2026

View reviewed changes

kevalmorabia97 reviewed Feb 6, 2026

View reviewed changes

shengliangxu approved these changes Feb 6, 2026

View reviewed changes

kevalmorabia97 reviewed Feb 6, 2026

View reviewed changes

Edwardf0t1 reviewed Feb 6, 2026

View reviewed changes

kaix-nv force-pushed the kaix/experimental branch 3 times, most recently from d6bcb38 to 8d6ee43 Compare February 6, 2026 23:55

kaix-nv enabled auto-merge (squash) February 6, 2026 23:57

Add contribution guidelines for experimental features

5b61480

Signed-off-by: Kai Xu <kaix@nvidia.com>

kaix-nv force-pushed the kaix/experimental branch from 8d6ee43 to 5b61480 Compare February 7, 2026 00:10

kaix-nv merged commit e53ca61 into main Feb 7, 2026
34 checks passed

kaix-nv deleted the kaix/experimental branch February 7, 2026 00:31

		@@ -0,0 +1,41 @@
		# SPDX-FileCopyrightText: Copyright (c) 2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved.


		## Path to Production

		When ready for production (proven effective, stable API, full tests, good docs), open an issue to propose graduating to the main `modelopt` package.

Conversation

kaix-nv commented Feb 6, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

Usage

Testing

Before your PR is "Ready for review"

Additional Information

Summary by CodeRabbit

Uh oh!

coderabbitai bot commented Feb 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Walkthrough

Changes

Estimated code review effort

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai bot Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

shengliangxu commented Feb 6, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kaix-nv Feb 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Feb 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shengliangxu left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kaix-nv commented Feb 6, 2026 •

edited by coderabbitai bot

Loading

coderabbitai bot commented Feb 6, 2026 •

edited

Loading

kaix-nv Feb 6, 2026 •

edited

Loading

codecov bot commented Feb 6, 2026 •

edited

Loading

shengliangxu left a comment •

edited

Loading